docs(plugin-kanban): document the badge element's colorClass / colorStyle members - #8134

Fixes #7984

packages/plugin-kanban/README.md's KanbanCard block documented the badges element with 2 of the 4 members carried by the shipped declaration. This adds colorClass and colorStyle in the shipped order, with one comment line naming the pairing rule. Source of truth: packages/types/src/complex.ts (KanbanCard at :63), which @object-ui/plugin-kanban re-exports through src/types.ts:36. No packages/** source is touched — the diff is 2 added lines in one README.

Side-by-side — the review IS the verification

No gate reds on this (see Why no gate holds it below), so please compare these by eye.

Shipped, packages/types/src/complex.ts:67-89 — JSDoc bodies elided to the load-bearing sentences; the full text is in the file:

  badges?: Array<{
    label: string;
    variant?: "default" | "secondary" | "destructive" | "outline";
    /**
     * Optional Tailwind class string applied to the badge. When set, it
     * overrides `variant` ...
     * Derive it the way the grid cell derives it, or the same option renders
     * two colours on one screen (objectui#5183): prefer
     * `getBadgeHexAppearance(color)` from `@object-ui/fields` and use its
     * `className` — passing its `colorStyle` too — and fall back to
     * `getBadgeColorClasses(color, value)` only when it returns `undefined`.
     */
    colorClass?: string;
    /**
     * Inline style accompanying `colorClass`. **Required whenever the class
     * string came from `getBadgeHexAppearance`** — that className reads CSS
     * custom properties which only this style declares, so a badge carrying
     * the class without the style references undefined variables. ...
     */
    colorStyle?: React.CSSProperties;
  }>;

README after this change, packages/plugin-kanban/README.md:129-135:

  badges?: Array<{
    label: string;
    variant?: 'default' | 'secondary' | 'destructive' | 'outline';
    colorClass?: string;
    colorStyle?: React.CSSProperties; // Required whenever colorClass came from getBadgeHexAppearance(color) in @object-ui/fields — the class reads CSS custom properties only this style declares (objectui#5183)
  }>;

Four member names, in the shipped order, with the shipped types (the README block's own single-quote convention for the variant union is kept, as is its // … trailing-comment style). The whole JSDoc is deliberately not transcribed — one line carries the pairing rule, which is the half a README reader cannot otherwise discover.

The pairing rule, in one line

A colorClass derived from getBadgeHexAppearance(color) (from @object-ui/fields) must be passed together with that helper's style as colorStyle, because the class reads CSS custom properties that only that style declares. A badge carrying the class without the style references undefined variables; deriving the class some other way is how one option renders two colours on one screen (objectui#5183).

Why no gate holds it (and why no gate was edited here)

Both boundaries are declared in the gates' own headers, so neither is a bug to patch:

• scripts/check-readme-exports.mjs compares top-level property names only, in both directions, and its :576 header says nested declarations are deliberately not walked. A nested member is outside the pin by design.
• packages/plugin-kanban/README.md is on scripts/check-doc-snippet-types.mjs's UNGATED_DOCS ledger at :728 (6 parse diagnostic(s) — blocks fenced ts that are bare object literals or elided bodies), so its fences are never compiled. That ledger is objectui#5174's shrink-only debt list and shrinking it has its own route.

Per the triage ruling on the card (§3), widening either gate is a separate card; this PR edits neither.

Reader named in the dispatch, measured after the change — node scripts/check-readme-exports.mjs --list, run on this branch's HEAD 6316cfd8:

matches            packages/plugin-kanban/README.md:125  interface KanbanCard  doc 7 key(s) + 0 method(s) vs own 7 of 7
matches            packages/plugin-kanban/README.md:114  interface KanbanColumn  doc 7 key(s) + 0 method(s) vs own 7 of 7

Still 7 vs 7, as predicted: the addition is nested, so the top-level pin sees nothing move.

Control that the page is still ungated — pnpm check:doc-snippets exit 0, and its census line still reads 227 document(s): 214 covered ..., 13 ungated — declared in this script, NOT verified by it, with this README among the 13. So React.CSSProperties in the block needs no import type today; nothing compiles it. It is written with the React. namespace spelling the shipped declaration uses, so it will still compile if and when this page comes off the ledger.

Scope notes

• objectui#6155 is open and records four disagreeing declarations of the KanbanCard / KanbanColumn pair. If whoever reconciles those moves this element, the README is re-touched once — one code block, a cheap second pass, and much cheaper than leaving a shipped README two members short indefinitely. That card is pm:blocked, and per triage this one is not mechanically blocked by it.
• objectui#5174 batch 26 is a likely pick for this README. This lands first; batch 26 re-reads the block.
• objectui#7742 (KanbanSchema's zero-read members and the root README's kanban example) is the same family on a different face and is not part of this PR.
• Last writer on this file was PR docs(plugins): bring three documented interface blocks up to their shipped types #7985 (objectui#7302), landed. Verified at branch-cut: no active branch touches this path — the four copilot/* kanban branches that differ on it last moved 2026-01-14 through 2026-02-04 and sit 200–1977 commits behind main, and claude/issue-5174-ungated-docs-batch25 does not touch it.

Gates

All run in this worktree at HEAD 6316cfd8, exit codes captured by redirect-then-capture:

Plus a self-scan of the changed path for control bytes: grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' packages/plugin-kanban/README.md exit 1 (no hits).

Changeset: none added. check-changeset-presence.mjs is the authority and it reads 1 file(s) changed, 0 of them published source of a package the release covers — a README is not published source to that script, so nothing is owed. No skip-changeset label was applied.

Live E2E (informational) is red on every branch today for an upstream reason (objectui#7990 / objectstack#16186) — not from this change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FhBNJcLRZLe8M87VcUgpKr

Generated by Claude Code